프론트엔드 API 게이트웨이: GraphQL Federation 및 Schema Stitching

최신 웹 애플리케이션 개발 세계에서 여러 소스로부터 데이터를 관리하는 것은 상당한 어려움이 될 수 있습니다. 애플리케이션이 복잡해지고 마이크로서비스 아키텍처를 채택함에 따라, 데이터에 접근하는 통합되고 효율적인 방법의 필요성이 무엇보다 중요해졌습니다. 프론트엔드 API 게이트웨이는 클라이언트 애플리케이션의 중앙 진입점 역할을 하며, 다양한 백엔드 서비스의 데이터를 집계하고 개발자와 최종 사용자 모두에게 간소화된 경험을 제공합니다. 이 블로그 게시물에서는 프론트엔드 API 게이트웨이를 구축하기 위한 두 가지 강력한 기술인 GraphQL Federation과 Schema Stitching을 살펴봅니다.

프론트엔드 API 게이트웨이란 무엇인가?

프론트엔드 API 게이트웨이는 전용 서버가 프론트엔드 클라이언트(예: 웹 브라우저, 모바일 앱)와 여러 백엔드 서비스 간의 중개자 역할을 하는 아키텍처 패턴입니다. 이는 다음과 같은 방법으로 데이터 페칭을 단순화합니다:

• 데이터 집계: 여러 소스의 데이터를 단일 응답으로 결합합니다.
• 데이터 변환: 프론트엔드의 요구에 맞게 데이터 형식을 조정합니다.
• 복잡성 추상화: 클라이언트로부터 백엔드 서비스의 복잡성을 숨깁니다.
• 보안 강화: 인증 및 인가 정책을 구현합니다.
• 성능 최적화: 자주 액세스하는 데이터를 캐싱하고 네트워크 요청을 줄입니다.

본질적으로, 이는 Backend for Frontend (BFF) 패턴을 대규모로 구현하며 프론트엔드 팀이 소비하는 API를 더 많이 제어할 수 있도록 권한을 부여합니다. 대규모 조직에서는 프론트엔드가 자체 API를 관리하고 큐레이션함으로써 더 빠른 제품 출시와 백엔드 팀에 대한 의존도 감소로 이어질 수 있습니다.

프론트엔드 API 게이트웨이에 GraphQL을 사용하는 이유

GraphQL은 API를 위한 쿼리 언어이자 기존 데이터로 해당 쿼리를 수행하기 위한 런타임입니다. 이는 기존의 REST API에 비해 여러 장점을 제공하여 프론트엔드 API 게이트웨이 구축에 매우 적합합니다:

• 효율적인 데이터 페칭: 클라이언트는 필요한 데이터만 요청하여 오버-페칭을 줄이고 성능을 향상시킵니다.
• 강력한 타이핑: GraphQL 스키마는 데이터 구조를 정의하여 더 나은 툴링과 유효성 검사를 가능하게 합니다.
• 인트로스펙션(Introspection): 클라이언트는 스키마 인트로스펙션을 통해 사용 가능한 데이터와 작업을 발견할 수 있습니다.
• 실시간 기능: GraphQL 구독(Subscription)은 실시간 데이터 업데이트를 가능하게 합니다.

GraphQL을 활용함으로써, 프론트엔드 API 게이트웨이는 여러 백엔드 서비스의 데이터에 접근하기 위한 유연하고 효율적이며 개발자 친화적인 인터페이스를 제공할 수 있습니다. 이는 각각 개별적으로 쿼리해야 하고 종종 필요 이상의 데이터를 반환하는 여러 REST 엔드포인트를 사용하는 기존 방식과 극명한 대조를 이룹니다.

GraphQL Federation: 분산 접근 방식

GraphQL Federation이란 무엇인가?

GraphQL Federation은 여러 GraphQL 서비스(서브그래프(subgraph)라 불림)를 단일 통합 스키마로 구성하여 분산 GraphQL API를 구축하는 강력한 기술입니다. 각 서브그래프는 특정 도메인 또는 데이터 소스를 담당하며, Federation 게이트웨이는 이러한 서브그래프 전반에 걸쳐 쿼리를 조율합니다.

핵심 개념은 전체 API를 나타내는 단일 통합 GraphQL 스키마인 슈퍼그래프(supergraph)를 중심으로 합니다. 이 슈퍼그래프는 각각 특정 마이크로서비스 또는 데이터 소스를 나타내는 더 작은 GraphQL 스키마, 즉 서브그래프(subgraph)들을 구성하여 구축됩니다. Federation 게이트웨이는 들어오는 GraphQL 쿼리를 적절한 서브그래프로 라우팅하고 결과를 단일 응답으로 결합하는 역할을 합니다.

GraphQL Federation의 작동 방식

1. 서브그래프 정의: 각 마이크로서비스는 자체 데이터와 작업을 정의하는 GraphQL API(서브그래프)를 노출합니다. 이 스키마에는 Federation 게이트웨이에 타입과 필드를 확인하는 방법을 알려주는 지시문(directive)이 포함됩니다. 주요 지시문으로는 `@key`, `@external`, `@requires`가 있습니다.
2. 슈퍼그래프 구성: Federation 게이트웨이(예: Apollo Gateway)는 각 서브그래프에서 스키마를 검색하여 단일 통합 스키마(슈퍼그래프)로 구성합니다. 이 과정에는 타입 및 필드 충돌 해결과 다른 서브그래프 간의 타입 관계 설정이 포함됩니다.
3. 쿼리 계획 및 실행: 클라이언트가 게이트웨이로 GraphQL 쿼리를 보내면 게이트웨이는 쿼리를 분석하여 요청을 처리하기 위해 어떤 서브그래프를 쿼리해야 하는지 결정합니다. 그런 다음 쿼리를 적절한 서브그래프로 분산하고 결과를 수집하여 클라이언트에게 반환될 단일 응답으로 결합합니다.

예시: GraphQL Federation을 사용한 전자상거래 플랫폼

제품, 고객, 주문을 위한 별도의 마이크로서비스가 있는 전자상거래 플랫폼을 생각해 봅시다.

• 제품 서브그래프: 제품 정보(이름, 설명, 가격 등)를 관리합니다.
• 고객 서브그래프: 고객 데이터(이름, 주소, 이메일 등)를 관리합니다.
• 주문 서브그래프: 주문 정보(주문 ID, 고객 ID, 제품 ID, 총액 등)를 관리합니다.

각 서브그래프는 GraphQL API를 노출하며, Federation 게이트웨이는 이러한 API들을 단일 슈퍼그래프로 구성합니다. 그러면 클라이언트는 슈퍼그래프에 쿼리하여 제품, 고객, 주문에 대한 정보를 단일 요청으로 검색할 수 있습니다.

예를 들어, 고객의 이름과 주문 내역을 검색하는 쿼리는 다음과 같을 수 있습니다:

query GetCustomerAndOrders($customerId: ID!) {
  customer(id: $customerId) {
    id
    name
    orders {
      id
      orderDate
      totalAmount
    }
  }
}

Federation 게이트웨이는 이 쿼리를 고객 및 주문 서브그래프로 라우팅하여 필요한 데이터를 검색하고 이를 단일 응답으로 결합합니다.

GraphQL Federation의 이점

• 단순화된 데이터 접근: 클라이언트는 기본 데이터 소스와 상관없이 단일 GraphQL 엔드포인트와 상호 작용합니다.
• 성능 향상: 각 서브그래프에서 필요한 데이터만 검색하여 데이터 페칭이 최적화됩니다.
• 확장성 증가: 각 서브그래프는 독립적으로 확장될 수 있어 더 나은 리소스 활용이 가능합니다.
• 분산 개발: 팀은 독립적으로 서브그래프를 개발하고 배포할 수 있어 민첩성과 혁신을 촉진합니다.
• 스키마 거버넌스: Federation 게이트웨이는 서브그래프 전반에 걸쳐 스키마 일관성과 호환성을 강제합니다.

GraphQL Federation을 위한 도구

• Apollo Federation: GraphQL Federation의 인기 있는 오픈 소스 구현으로, 게이트웨이, 스키마 레지스트리, 페더레이션된 GraphQL API를 구축하고 관리하기 위한 툴링을 제공합니다. Apollo Federation은 확장성과 강력한 오류 처리로 유명합니다.
• GraphQL Hive: 이 도구는 GraphQL 페더레이션 서비스를 위한 스키마 레지스트리 및 거버넌스를 제공하며, 변경 감지, 사용량 분석, 스키마 검사와 같은 기능을 제공합니다. 이는 슈퍼그래프에 대한 가시성과 제어를 향상시킵니다.

Schema Stitching: 대안적 접근 방식

Schema Stitching이란 무엇인가?

Schema Stitching은 여러 GraphQL 스키마를 단일 통합 스키마로 결합하는 또 다른 기술입니다. Federation과 달리 Schema Stitching은 일반적으로 다른 스키마의 타입과 필드가 어떻게 연결되는지 정의하는 데 더 수동적인 과정을 포함합니다. Federation이 더 현대적이고 견고한 솔루션으로 간주되지만, Schema Stitching은 더 간단한 사용 사례나 기존 GraphQL API에서 마이그레이션할 때 실행 가능한 옵션이 될 수 있습니다.

Schema Stitching의 작동 방식

1. 스키마 정의: 각 마이크로서비스는 자체 스키마를 가진 GraphQL API를 노출합니다.
2. 스티칭 로직: 스티칭 계층(종종 GraphQL Tools와 같은 라이브러리를 사용하여 구현됨)은 다른 스키마의 타입과 필드가 어떻게 연결되는지 정의합니다. 여기에는 기본 서비스에서 데이터를 가져와 통합 스키마에 매핑하는 리졸버(resolver) 함수를 작성하는 것이 포함됩니다.
3. 통합 스키마: 스티칭 계층은 개별 스키마를 클라이언트에 노출되는 단일 통합 스키마로 결합합니다.

예시: 제품과 리뷰 스티칭

제품용과 리뷰용, 두 개의 별도 GraphQL 서비스가 있다고 상상해 봅시다.

• 제품 서비스: 제품에 대한 정보(ID, 이름, 설명, 가격)를 제공합니다.
• 리뷰 서비스: 제품에 대한 리뷰(ID, 제품 ID, 평점, 코멘트)를 제공합니다.

Schema Stitching을 사용하여 클라이언트가 단일 쿼리로 제품 정보와 리뷰를 검색할 수 있는 통합 스키마를 만들 수 있습니다.

스티칭 계층에서 주어진 제품 ID에 대한 리뷰를 리뷰 서비스에서 가져와 통합 스키마의 Product 타입에 추가하는 리졸버 함수를 정의하게 됩니다.

// 예시 (개념적): GraphQL Tools를 사용한 스티칭 로직
const { stitchSchemas } = require('@graphql-tools/stitch');

const productsSchema = ... // 제품 스키마 정의
const reviewsSchema = ... // 리뷰 스키마 정의

const stitchedSchema = stitchSchemas({
  subschemas: [
    {
      schema: productsSchema,
    },
    {
      schema: reviewsSchema,
      transforms: [
        {
          transformSchema: (schema) => schema,
          transformRequest: (originalRequest) => {
            return originalRequest;
          },
          transformResult: (originalResult) => {
            return originalResult;
          }
        }
      ],
    },
  ],
  typeDefs: `
    extend type Product {
      reviews: [Review]
    }
  `,
  resolvers: {
    Product: {
      reviews: {
        resolve: (product, args, context, info) => {
          // Reviews 서비스에서 해당 제품의 리뷰를 가져옴
          return fetchReviewsForProduct(product.id);
        },
      },
    },
  },
});

이 예시는 스키마를 함께 스티칭하는 핵심 개념을 보여줍니다. `reviews` 필드를 가져오기 위해 커스텀 리졸버가 필요하다는 점에 유의하십시오. 각 관계에 대해 리졸버를 코딩해야 하는 이러한 추가적인 오버헤드는 개발 과정을 Federation을 사용하는 것보다 느리게 만들 수 있습니다.

Schema Stitching의 이점

• 통합 API: 클라이언트는 단일 GraphQL 엔드포인트에 액세스하여 데이터 접근을 단순화합니다.
• 점진적 도입: Schema Stitching은 점진적으로 구현할 수 있어 통합 API로 점차 마이그레이션할 수 있습니다.
• 유연성: Schema Stitching은 스키마를 결합하는 방법에 대해 더 많은 제어권을 제공하여 특정 요구에 맞게 스티칭 로직을 사용자 정의할 수 있습니다.

Schema Stitching의 단점

• 수동 설정: Schema Stitching은 스티칭 로직의 수동 설정을 필요로 하며, 이는 복잡하고 시간이 많이 걸릴 수 있습니다.
• 성능 오버헤드: 리졸버 함수는 특히 복잡한 데이터 변환을 포함하는 경우 성능 오버헤드를 유발할 수 있습니다.
• 제한된 확장성: Schema Stitching은 스티칭 로직이 일반적으로 중앙 집중화되어 있어 Federation보다 확장하기가 더 어려울 수 있습니다.
• 스키마 소유권: 특히 다른 팀이 스티칭된 서비스를 관리하는 경우 스키마 소유권에 대한 모호성을 유발할 수 있습니다.

Schema Stitching을 위한 도구

• GraphQL Tools: Schema Stitching 지원을 포함하여 GraphQL 스키마를 구축하고 조작하기 위한 인기 있는 라이브러리입니다.
• GraphQL Mesh: GraphQL Mesh를 사용하면 GraphQL 쿼리 언어를 사용하여 REST API, 데이터베이스, gRPC와 같은 다양한 소스의 데이터에 액세스할 수 있습니다. 이러한 API들을 통합된 GraphQL 스키마로 스티칭할 수 있습니다.

GraphQL Federation vs. Schema Stitching: 비교

GraphQL Federation과 Schema Stitching은 모두 여러 GraphQL 스키마를 단일 API로 결합하는 방법을 제공하지만, 접근 방식과 기능 면에서 차이가 있습니다.

기능	GraphQL Federation	Schema Stitching
접근 방식	분산적, 자동화된 구성	중앙 집중적, 수동 설정
복잡성	유지 및 확장에 대한 복잡성 낮음	수동 리졸버 로직으로 인한 복잡성 높음
확장성	대규모 분산 시스템을 위해 설계됨	확장성이 낮고, 일반적으로 소규모 애플리케이션에 사용됨
스키마 거버넌스	내장된 스키마 거버넌스 및 유효성 검사	수동 스키마 관리 및 조정 필요
툴링	강력한 도구 및 라이브러리 생태계 (예: Apollo Federation)	더 많은 커스텀 툴링 및 설정 필요
사용 사례	마이크로서비스 아키텍처, 대규모 API, 분산 개발	소규모 애플리케이션, 점진적 마이그레이션, 특정 커스터마이징 요구사항

GraphQL Federation을 사용해야 할 때: 복잡한 마이크로서비스 아키텍처를 가지고 있고, API를 확장해야 하며, 독립적인 팀이 자체 서브그래프를 관리하도록 권한을 부여하고 싶을 때 Federation을 선택하십시오. 또한 스키마 관리와 거버넌스를 단순화합니다.

Schema Stitching을 사용해야 할 때: 더 간단한 API를 가지고 있거나, 스티칭 로직에 대한 더 많은 제어가 필요하거나, 기존 GraphQL API에서 마이그레이션하는 경우 Schema Stitching을 고려하십시오. 그러나 잠재적인 복잡성과 확장성 제한에 유의해야 합니다.

인증 및 인가 구현

GraphQL Federation이나 Schema Stitching 중 어느 것을 선택하든, 프론트엔드 API 게이트웨이를 보호하기 위해 인증 및 인가를 구현하는 것은 매우 중요합니다. 다음과 같은 몇 가지 접근 방식을 취할 수 있습니다:

• 게이트웨이 수준 인증: API 게이트웨이는 요청을 백엔드 서비스로 라우팅하기 전에 인증 및 인가를 처리합니다. 이 접근 방식은 보안 로직을 중앙 집중화하고 백엔드 서비스를 단순화합니다. 일반적인 방법으로는 JWT(JSON 웹 토큰) 검증과 OAuth 2.0이 있습니다.
• 서비스 수준 인증: 각 백엔드 서비스가 자체 인증 및 인가를 처리합니다. 이 접근 방식은 보안에 대한 더 세분화된 제어를 제공하지만 관리하기가 더 복잡할 수 있습니다.
• 하이브리드 접근 방식: 게이트웨이 수준과 서비스 수준 인증의 조합입니다. 게이트웨이가 초기 인증을 처리하고 백엔드 서비스가 더 세분화된 인가 확인을 수행합니다.

예시: Apollo Federation을 사용한 JWT 인증

Apollo Federation을 사용하면 게이트웨이가 요청 헤더에 포함된 JWT 토큰을 검증하도록 설정할 수 있습니다. 그러면 게이트웨이는 토큰에서 추출한 사용자 정보를 서브그래프로 전달할 수 있으며, 서브그래프는 이 정보를 인가에 사용할 수 있습니다.

// 예시 (개념적): JWT 검증을 포함한 Apollo Gateway 설정
const { ApolloGateway } = require('@apollo/gateway');

const gateway = new ApolloGateway({
  serviceList: [
    // ... 서브그래프 설정
  ],
  buildService: ({ name, url }) => {
    return new MyCustomService({
      name,  // 서브그래프 이름
      url,   // 서브그래프 URL
    });
  },
});

class MyCustomService extends RemoteGraphQLDataSource {
  willSendRequest({ request, context }) {
    // 컨텍스트에서 사용자 정보 가져오기
    const user = context.user;

    // 요청 헤더에 사용자 ID 추가
    if (user) {
      request.http.headers.set('user-id', user.id);
    }
  }
}

이 예시에서는 JWT에서 파생된 사용자 ID를 포함하도록 나가는 요청을 수정하기 위해 커스텀 서비스가 생성됩니다. 다운스트림 서비스는 이 ID를 인가 확인에 사용할 수 있습니다.

성능 최적화를 위한 캐싱 전략

캐싱은 프론트엔드 API 게이트웨이의 성능을 향상시키는 데 필수적입니다. 자주 액세스하는 데이터를 캐싱함으로써 백엔드 서비스의 부하를 줄이고 클라이언트의 응답 시간을 개선할 수 있습니다. 다음은 몇 가지 캐싱 전략입니다:

• HTTP 캐싱: HTTP 캐싱 메커니즘(예: `Cache-Control` 헤더)을 활용하여 브라우저와 중간 프록시에 응답을 캐시합니다.
• 인메모리 캐싱: 인메모리 캐시(예: Redis, Memcached)를 사용하여 게이트웨이에서 자주 액세스하는 데이터를 캐시합니다.
• CDN 캐싱: 콘텐츠 전송 네트워크(CDN)를 활용하여 정적 자산과 API 응답을 클라이언트와 더 가까운 곳에 캐시합니다.
• GraphQL 쿼리 캐싱: GraphQL 쿼리의 결과를 쿼리 문자열과 변수를 기반으로 캐시합니다. 이는 자주 실행되는 쿼리에 특히 효과적일 수 있습니다. Apollo Server는 쿼리 캐싱을 내장 지원합니다.

캐싱을 구현할 때는 클라이언트가 최신 데이터를 받도록 캐시 무효화 전략을 고려해야 합니다. 일반적인 전략은 다음과 같습니다:

• 시간 기반 만료: 캐시된 데이터에 고정된 만료 시간을 설정합니다.
• 이벤트 기반 무효화: 백엔드 서비스에서 데이터가 변경될 때 캐시를 무효화합니다. 이는 웹훅이나 메시지 큐를 사용하여 달성할 수 있습니다.

모니터링 및 관찰 가능성

모니터링과 관찰 가능성은 프론트엔드 API 게이트웨이의 상태와 성능을 보장하는 데 매우 중요합니다. 다음과 같은 주요 지표를 추적하기 위해 포괄적인 모니터링을 구현하십시오:

• 요청 지연 시간: 요청을 처리하는 데 걸리는 시간입니다.
• 오류율: 오류를 발생시키는 요청의 비율입니다.
• 처리량: 단위 시간당 처리되는 요청 수입니다.
• 리소스 사용률: 게이트웨이 및 백엔드 서비스의 CPU, 메모리, 네트워크 사용량입니다.

추적(tracing)을 사용하여 시스템을 통해 흐르는 요청을 추적하고 병목 현상과 성능 문제를 식별하십시오. 로깅은 게이트웨이 및 백엔드 서비스의 동작에 대한 귀중한 통찰력을 제공합니다.

모니터링 및 관찰 가능성을 위한 도구는 다음과 같습니다:

• Prometheus: 오픈 소스 모니터링 및 경고 시스템입니다.
• Grafana: 데이터 시각화 및 모니터링 도구입니다.
• Jaeger: 오픈 소스 분산 추적 시스템입니다.
• Datadog: 클라우드 애플리케이션을 위한 모니터링 및 보안 플랫폼입니다.
• New Relic: 소프트웨어 성능을 모니터링하고 개선하기 위한 디지털 인텔리전스 플랫폼입니다.

강력한 모니터링과 관찰 가능성을 구현함으로써 문제를 사전에 식별하고 해결하여 프론트엔드 API 게이트웨이의 안정성과 성능을 보장할 수 있습니다.

결론

GraphQL Federation 또는 Schema Stitching으로 구축된 프론트엔드 API 게이트웨이는 최신 웹 애플리케이션에서 데이터 접근을 크게 단순화하고 성능을 개선하며 개발자 경험을 향상시킬 수 있습니다. GraphQL Federation은 분산 GraphQL API를 구성하기 위한 강력하고 확장 가능한 솔루션을 제공하는 반면, Schema Stitching은 기존 스키마를 결합하기 위한 더 유연한 접근 방식을 제공합니다. 애플리케이션의 특정 요구 사항과 이러한 기술 간의 장단점을 신중하게 고려함으로써 견고하고 효율적인 프론트엔드 API 게이트웨이를 구축하기 위한 최상의 접근 방식을 선택할 수 있습니다.

게이트웨이의 보안, 성능 및 안정성을 보장하기 위해 적절한 인증 및 인가, 캐싱 전략, 모니터링 및 관찰 가능성을 구현하는 것을 잊지 마십시오. 이러한 모범 사례를 채택함으로써 GraphQL의 잠재력을 최대한 활용하고 탁월한 사용자 경험을 제공하는 최신 웹 애플리케이션을 구축할 수 있습니다.